Prevent stale 404s for files written by another realm-server instance - #5923

[Claude Code 🤖] (Written by Claude on Matic's behalf.) Fixed: the refresh now lists every ancestor from the realm root down to the immediate parent (ancestorDirectories), so a parent directory the peer had cached as absent is refreshed before its children are looked up. Covered by the new directory-view-refresher-test.ts.

[Claude Code 🤖] (Written by Claude on Matic's behalf.) Fixed both parts: NodeAdapter.readdir now uses fs.promises-style readdir (the sync helper it used is removed), and the refresh logic moved into DirectoryViewRefresher, which coalesces per directory — while a listing is in flight, later requests share it and at most one follow-up is queued behind it. A batch write into one directory therefore costs a bounded number of listings instead of one per file; the test asserts listings never overlap and that five concurrent refreshes produce fewer listings than refreshes.

Queue another listing during the follow-up refresh

When three notifications for the same directory overlap, the first starts current, the second creates queued, and any notification arriving after that—even while the queued listing is already running—takes this branch and schedules nothing after it. If that already-started NFS listing did not observe the latest write, its negative entry remains cached and the peer can continue returning the stale 404 this change is intended to eliminate. Promote the follow-up to the current listing when it starts so arrivals during it can queue one additional refresh.

Useful? React with 👍 / 👎.

[Claude Code 🤖] (Written by Claude on Matic's behalf.) Fixed: #startListing now installs the follow-up as the running listing when it begins (replacing the predecessor entry), so a request that arrives during it queues one more listing instead of sharing one that started before its write. New test covers the three-arrival scenario.

[Claude Code 🤖] One failing ancestor cancels the rest of the chain, including the immediate parent — the directory whose refresh is the entire point of the call.

I ran this against the real class: refresh('a/b/c.json') where the listing of '' rejects lists '' and nothing else — a and a/b never run, and the listener's .catch only logs a warning, so the stale 404 stands for the full attribute-cache TTL. The realm root is the ancestor least likely to need refreshing (it always exists) and the one whose failure is most expensive, since it is listed first. Continuing is strictly better: when a/b already exists in this instance's view — the common case — listing it alone is what clears the file's negative entry.

async refresh(path: LocalPath): Promise<void> {
  let errors: unknown[] = [];
  for (let directory of ancestorDirectories(path)) {
    try {
      await this.#list(directory);
    } catch (err) {
      errors.push(err);
    }
  }
  if (errors.length) {
    throw errors.length === 1 ? errors[0] : new AggregateError(errors);
  }
}

Related, same containment gap on a different axis: #list has no timeout, and a listing that never settles is never replaced in #listings, so every later refresh for that directory queues behind it for the life of the process rather than for the duration of the hang. I confirmed that too — with a lister returning a never-resolving promise, the second refresh's listing never starts. A hard-mounted NFS/EFS hanging is the failure mode worth defending against here; reads still self-heal on the kernel TTL, so this is durability of the refresher, not correctness.

Regression (introduced here), non-blocking.

Generated by Claude Code

[Claude Code 🤖] (Written by Claude on Matic's behalf.) Fixed both parts: refresh() now collects per-ancestor errors and keeps walking (single error re-thrown as-is, several as an AggregateError), and every listing is wrapped in a timeout (default 15 s, constructor-injectable) that releases the per-directory slot so a hung filesystem call cannot block later refreshes for the life of the process. The timeout does not cancel the underlying listing; a fresh one may overlap it, which is safe for reads. Tests cover the failing-root chain and the hung-listing recovery.

[Claude Code 🤖] Is the bulk branch meant to stay uncovered? It is the same stale-view bug over a whole realm instead of one path.

handle-publish-realm.ts swaps the realm directory on disk and then calls clearLocalSourceCachesAndBroadcast(). That drops peers' byte caches but leaves their kernel view of the swapped tree untouched, so a peer that still has the republished realm mounted can 404 every file the new snapshot added, for the same tens of seconds. Unpublish and delete are covered incidentally — the realm is unmounted there, so lookupMountedRealm returns undefined and the notification is dropped before this branch ever runs — but republish is not.

Either wire something in here or say in the PR that it's a follow-up; as it stands the wildcard branch reads as handled. realm.refreshDirectoryView('') is a one-line partial that covers top-level files (ancestorDirectories('') is just ['']); covering nested files needs a recursive walk, which is a real cost decision and probably its own change.

Pre-existing, now load-bearing — this PR establishes the mechanism that makes the gap visible. Non-blocking.

Generated by Claude Code

[Claude Code 🤖] (Written by Claude on Matic's behalf.) Follow-up, deliberately: covering republish needs a recursive walk of the swapped tree, which is a cost decision that deserves its own change. The listener's wildcard comment now says explicitly that the kernel view is NOT refreshed there and what the consequence is, so the branch no longer reads as handled.

[Claude Code 🤖] These three assertions are weaker than the contract they name — count(dir) < names.length passes at 4 listings out of 5 refreshes, so a regression that degraded coalescing to one-follow-up-per-notification stays green.

The root count here is structurally forced, not timing-dependent: names.map(...) calls refresh synchronously, and each refresh runs to its first await this.#list('') synchronously, so the first call starts a listing and the other four all attach to the same pending. I ran this scenario against the refresher directly — 20 trials at each of 0/1/5/20 ms listing latency — and the root count was exactly 2 every time. Assert that instead; it subsumes both rootCoalesced and followUpRan:

assert.strictEqual(count(''), 2, 'root listed once, then one follow-up for the four that arrived during it');
assert.true(count('PersonCard') <= 3, `PersonCard listings stayed bounded (${count('PersonCard')})`);

PersonCard came back as 3 in all 80 runs, but unlike root it depends on the interleaving of the root follow-up and the first PersonCard listing, so a bound rather than an equality is the honest assertion there.

Regression in test strength (this file is new), non-blocking.

Generated by Claude Code

[Claude Code 🤖] (Written by Claude on Matic's behalf.) Applied as suggested: the root count is asserted as exactly 2 with a comment explaining why it is structurally forced, and PersonCard as a ≤3 bound.

[Claude Code 🤖] Worth confirming the per-write listing budget is what you want: every single-path notification now lists the realm root plus each intermediate directory, on every instance that has the realm mounted — including the instance that emitted the NOTIFY, since pg_notify goes out on a pooled connection and comes back on this process's own dedicated LISTEN connection. Realm.clearLocalSourceCachesAndBroadcast's comment already records that self-receive happens and calls it free, which it was for an idempotent in-memory clear. It isn't free for an EFS round trip, and the writer's own view is the one that's already correct.

The root listing is the expensive half on a user realm whose cards sit at the top level, and it's only needed when the write created a new intermediate directory. A cheaper shape: have the lister hand back the entry names, list the immediate parent first, and walk the rest of the chain only when the written basename isn't in it — which also covers the stale-parent case, since a parent that's still cached as absent lists as empty.

Non-blocking, and a decision rather than a defect — if the current budget is deliberate, a line in the header comment saying so would settle it.

Generated by Claude Code

[Claude Code 🤖] (Written by Claude on Matic's behalf.) Kept the current budget and documented it as deliberate in the header comment: realm trees are shallow, bursts coalesce per directory, and the walk-up-only-when-missing shape would trade that simplicity for savings mostly on the root listing. Worth revisiting if per-write listing cost ever shows up in the prerender/indexing telemetry.